home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Applications 2004 May / SGI IRIX 6.5 Applications 2004 May.iso / dist / java3d.idb / usr / demos / java / j3d / programs / examples / Sound / README.release.z / README.release
Encoding:
Text File  |  2003-08-08  |  10.9 KB  |  227 lines

  1. /*
  2.  *    @(#)README.release 1.7 01/10/14 09:42:38
  3.  *
  4.  * Copyright (c) 1996-2001 Sun Microsystems, Inc. All Rights Reserved.
  5.  */
  6.  
  7. ==========================================================================
  8. Java 3D(TM) Sound 1.3 Beta 1
  9. ==========================================================================
  10.  
  11. Java 3D sound is rendered via the use of a specific implementation
  12. of the AudioDevice3D interface.   This release includes two AudioDevice3DL2
  13. implementations.
  14.  
  15. = = = = = = = = = = = = = = = = = = = = = = = 
  16. HeadspaceMixer AudioDevice3DL2 Implememtation
  17. = = = = = = = = = = = = = = = = = = = = = = = 
  18.  
  19.    The HeadspaceMixer implementation is part of the Sun Java 3D 
  20.    com.sun.j3d.audioengines.headspace package.  This implementation
  21.    uses a version of the Headspace Audio Engine licensed from Beatnik
  22.    which does all rendering in software and pipes the stereo audio image 
  23.    to the platform's audio device.
  24.  
  25.    The implemention that was called JavaSoundMixer in previous Sun 
  26.    releases of Java 3D has been renamed to HeadspaceMixer.
  27.    It was renamed in enticipation of the release of a new AudioDevice
  28.    implementation that uses JavaSound API which will be called JavaSoundMixer
  29.    (described below).
  30.  
  31.    The HeadspaceMixer audio device will be created and initialized when the
  32.    utility SimpleUniverse.Viewer.createAudioDevice() method is called.
  33.    If your application uses this utility, no change will be required to
  34.    use the recommended HeadspaceMixer implementation.
  35.  
  36.    If your application explicitly used the older JavaSoundMixer audio device 
  37.    implemention from the package com.sun.j3d.audioengines.javasound, you should
  38.    change the reference to JavaSoundMixer, at least for this Beta 1 release,
  39.    to HeadspaceMixer:
  40.  
  41.           import com.sun.j3d.audioengines.headspace.HeadspaceMixer;
  42.              :
  43.           HeadspaceMixer mixer = new HeadspaceMixer(physicalEnvironment);
  44.  
  45.    Most of the Java 3D Audio features have been implemented but there are
  46.    a few exceptions.  Additionally, some Java 3D Audio features are only
  47.    only partially implemented.
  48.  
  49.    Hang under JDK 1.3 on Windows platforms
  50.    ---------------------------------------
  51.    Occationally, some applications when run under JDK 1.3 on Windows 
  52.    experienced window manager hangs.  This problem could not be produced
  53.    under JDK 1.4.  It is recommended that if this problem arrises with
  54.    your application that JDK 1.4 be used.
  55.  
  56.    Audio Features Not Supported with this release:
  57.    -----------------------------------------------
  58.       - Cross-talk cancellation is not performed when rendered audio output
  59.         on speakers.
  60.       - Spatialization of positional and directional sound is very rudimentary.
  61.         Point and Cone sound will simply be panned (approximating interaural
  62.         intensity difference)  and left-right output signals delayed
  63.         (approximating interaural delay difference) applying gain attenuation.
  64.       - The filtering of sound source (that would aid in Elevation or Front/
  65.         Back differentiation cues) is not implemented with this AudioDevice.
  66.       - For this release, distance and angular low-pass filtering of sound
  67.         sources is implemented with a very simple algorithm (that choose speed
  68.         over accuracy).
  69.       - For this release, Sound.POSITIVE_INFINITY is mapped to 2^15.
  70.  
  71.    Supported MediaContainers data
  72.    ------------------------------
  73.       This engine supports 8- and 16- bit linear, and u-law and A-law formatted
  74.       files in mono and stereo AU, AIFF, WAV, and PCM file formats.
  75.       Compressed formats such as DVI, GSM, and MOD are not supported at this
  76.       time.  Encoded format such as MP3 are not supported.
  77.  
  78.       MIDI and RMF files are supported but not fully spatialized.
  79.       MIDI file playback as BackgroundSound and attenuated Point/ConeSounds
  80.       is at least partially supported with the following limitations:
  81.       - For this release MIDI data is automatically cached.
  82.       - Point/ConeSound nodes that use MIDI MediaContainers can not be 
  83.         panned or delayed to simulate Interaural Intensity or Time 
  84.         Differences due to the limitiation of the underlying technology
  85.         used in this implementation.
  86.  
  87.       InputStreams as MediaContainers are not supported for Point or
  88.         ConeSounds in this implementation.
  89.  
  90.    Reverberation
  91.    -------------
  92.       The Headspace engine supports these 5 reverberation environments:
  93.           "Closet"         very small area, very absorptive surfaces
  94.           "Acoustic Lab"   med. small area,  equally absorptive/reflective
  95.           "Garage"         med. large area, somewhat reflective surfaces
  96.           "Dungeon"        medium area, reflective surfaces
  97.           "Cavern"         large area, highly reflective surfaces
  98.  
  99.       The AuralAttributes parameters dealing with reverb -
  100.       early and late reflection coefficient and delay time, reverb decay
  101.       time - are compared to choose one of these five software aural
  102.       environments offered as part of the Headspace engine. 
  103.       Decay speed, paired with the explicit or implicit size of the space,
  104.       determine the Headspace Reverb type that is set:
  105.  
  106.                                |  Short:               Long:
  107.             Size    Delay Time |    Decay <= 1500ms      Decay > 1500ms
  108.            ---------------------------------------------------------------
  109.             small   (< 100ms)  |    2 "Closet"           4 "Acoustic Lab"
  110.             medium  (<=500ms)  |    3 "Garage"           6 "Dungeon"
  111.             large   (> 500ms)  |    6 "Dungeon"          5 "Cavern"
  112.  
  113.       A "feature" of this engines 'Dungeon' reverb type is that the
  114.       reverberation is added to the opposite pan position from the
  115.       sound's position.  This creates an aural effect that sounds
  116.       like the reverberation is bouncing off the opposite wall of
  117.       the 'Dungeon'.
  118.  
  119. = = = = = = = = = = = = = = = = = = = = = = = 
  120. JavaSoundMixer AudioDevice3DL2 Implememtation
  121. = = = = = = = = = = = = = = = = = = = = = = = 
  122.  
  123.    The JavaSoundMixer implementation is part of the Sun Java 3D 
  124.    com.sun.j3d.audioengines.javasound package.  This implementation uses
  125.    the Java Sound API.  All low-level access to the platforms audio device
  126.    are dependent on the Java Sound mixer implementation(s) installed on
  127.    the machine you're running on.
  128.  
  129.    The JavaSoundMixer Java 3D audio device implementation uses Java Sound
  130.    SourceDataLine streams for non-cached data and Java Sound Clips for
  131.    cached data.  Support for specific sound cards, the exact input formats
  132.    that can be passed as data to Java 3D MediaContainers, and which feature
  133.    are rendered in software verses accelleration hardware is dependent on
  134.    the Java Sound implementation installed on your machine.
  135.    There is guarenteed to be at least one Java Sound mixer implementation
  136.    available with all J2SE releases (such as Sun's JDK 1.3 and above).
  137.  
  138.    Audio Features Not Supported with this release:
  139.    -----------------------------------------------
  140.       The JavaSoundMixer is a brand new implementation as of 1.3 Beta 1
  141.       release.  While much of the Java 3D Audio API has been implemented
  142.       but there are known problems and limitations. Additionally, some Java
  143.       3D Audio features are only partially implemented.
  144.  
  145.       - Non-linear file formats (A-law and u-law) are not converted.
  146.       - MIDI files for all sound types are not implemented.
  147.       - There are several timing and channel synchronization problems
  148.         encountered when Point and Cone Sounds are rendered.
  149.       - Distance and angular low-pass filtering of sound source is not 
  150.         implemented.
  151.       - Spatialization of positional and directional sound is very rudimentary.
  152.         See notes above under HeadspaceMixer.
  153.       - Cross-talk cancellation for speaker playback is not performed.
  154.  
  155.       Until these isues are fixed in next Beta 2 release it is recommended
  156.       that you use the the HeadspaceMixer implementation.
  157.  
  158.    Supported MediaContainers data
  159.    ------------------------------
  160.       The intent is that all MediaContainer input data types supported by 
  161.       Java Sound will also be supported by the JavaSoundMixer implementation.
  162.       This implementation will not have the restrictions on InputStreams as
  163.       the HeadspaceMixer implementation has.
  164.  
  165.    Reverberation
  166.    -------------
  167.       Java 3D reverberation parameters map to a corresponding set
  168.       reverb control parameters available thru JavaSound API for Clips
  169.       (cached MediaContainers).  The exact auralization rendering based
  170.       on these parameters is dependent on the Java Sound mixer implementation
  171.       choosen.
  172.  
  173. = = = = = = = = = = = = = = = = = = = = = = = 
  174. Use
  175. = = = = = = = = = = = = = = = = = = = = = = = 
  176. Any Java 3D program that wants to render sounds must create and initialize
  177. an instance of either HeadspaceMixer or JavaSoundMixer directly or indirectly
  178. (using SimpleUniverse utilities).
  179.  
  180. All of the sound example programs included in this release use the 
  181. com.sun.j3d.utils.universe.SimpleUniverse class to create and initialize
  182. an instance of the HeadspaceMixer with the following code:
  183.  
  184.         Canvas3D c = new Canvas3D(null);
  185.         SimpleUniverse u = new SimpleUniverse(c);
  186.         AudioDevice audioDev = u.getViewer().createAudioDevice();
  187.  
  188. As application can initialize the HeadspaceMixer implementation directly
  189. with code like following:
  190.      
  191.     import com.sun.j3d.audioengines.headspace.HeadspaceMixer;
  192.            :
  193.     Canvas3D canvas = new Canvas3D(null);
  194.     SimpleUniverse univ = new SimpleUniverse(canvas);
  195.     univ.getViewingPlatform().setNominalViewingTransform();
  196.     PhysicalEnvironment physicalEnv = 
  197.            univ.getViewer().getPhysicalEnvironment();
  198.     if (physicalEnv != null) {
  199.         HeadspaceMixer mixer = new HeadspaceMixer(physicalEnv);
  200.         if (mixer == null) 
  201.             System.out.println("creation of audio device failed");
  202.         mixer.initialize();
  203.     }
  204.  
  205. NOTE: Sun JDK has an implementation of the javax.sound.sampled.Mixer
  206. interface named 'HeadspaceMixer'.  If your application also imports the
  207. javax.sound.sampled package you'll need to explicitly differentiate by
  208. specifying the full Java 3D package when referencing HeadspaceMixer:
  209.              :
  210.         com.sun.j3d.audioengines.headspace.HeadspaceMixer mixer = 
  211.              new com.sun.j3d.audioengines.headspace.HeadspaceMixer(physicalEnv);
  212.              :
  213.  
  214.  
  215. ==========================================================================
  216. General Installation Notes:
  217. ==========================================================================
  218.       If your Java 3D application has trouble acquiring the AudioDevice
  219.       ("Audio Device unavailable" exception occurs) you may need to exit
  220.       other applications that use sound.  NOTE: If this occurs we would
  221.       appreciate being informed as to which sound application Java 3D had
  222.       problems running simultaneously with.
  223.  
  224.       Combining calls to JMF 1.0 methods in your Java 3D sound application
  225.       is still dangerous.  The engines used by both APIs may not yet be
  226.       robust enough to handle supporting both of these concurrently.
  227.